tsconfig | the missing docs

The tsconfig.json file serves as the configuration file for a TypeScript project. By placing this file in a directory, you declare that directory as the root of your TypeScript project.

Here's an updated example of a tsconfig.json file:

{
  "compilerOptions": {
    "module": "commonjs",
    "noImplicitAny": true,
    "target": "es2023",
    "baseUrl": "./",
    "rootDir": "./",
    "outDir": "dist/",
    "removeComments": true,
    "lib": ["es2023", "dom"],
    "preserveConstEnums": true,
    "sourceMap": true
  },
  "files": [
    "src/file3.ts"
  ],
  "include": [
    "./src/"
  ],
  "exclude": [
    "./src/file2.ts",
    "./src/file3.ts"
  ]
}

Key Takeaways

• The tsconfig.json file configures the TypeScript compiler options.
• The include and exclude options control which files to compile.
• paths and baseUrl simplify module resolution.
• target dictates the ECMAScript version for compiled output.
• The configuration affects both the compilation process and the structure of output files.

tsconfig Include

The include property specifies the files to include within the TypeScript project. Utilize file patterns like ./src/** for broad inclusivity.

tsconfig Exclude

The exclude property indicates files to be excluded from the TypeScript project. Entries here will override those in include.

tsconfig Files

The files property lists specific files to include. This does not support pattern matching and overrides exclude.

Bear in mind:

• files overrides exclude.
• exclude overrides include.
• Files referenced within files or include are also included.

In the example, file3.ts is included, but file2.ts is not compiled.

tsconfig Paths

The optional paths setting allows you to specify custom path mappings. These mappings serve as aliases.

"paths": {
  "mylibs/*": ["./src/libs/utils/*"]
}

This usage enables simplified imports:

import { myFunc } from "mylibs/math"

Compared to the direct relative path import:

import { myFunc } from "../libs/utils/math"

Ensure a baseUrl is specified to avoid errors.

tsconfig Target

The target option sets the ECMAScript version the TypeScript compiles to. In modern settings, specifying es2023 helps optimize usage of new JavaScript features.

If you don't specify, the default is ES3. The esnext target is also available for acquiring the latest stable features.

tsconfig Lib

The lib option specifies libraries you wish to include. By default, TypeScript includes essential libraries, but you can extend them as necessary.

In the example, [{ "es2023", "dom" }] is configured to include ES2023 APIs and DOM interfaces.

tsconfig BaseUrl and OutDir

The baseUrl identifies the root directory for module resolution. Similarly, outDir sets the destination for compiled output files, defaulting otherwise to the directory of the source files.

tsconfig RootDir

The rootDir option gives further control over compiled output directory structure. Set it to organize how source files are included in the output optimally.

tsconfig AllowJs

The allowJs option lets you include JavaScript files in your project. Set it to true to permit JavaScript file imports without errors.

FAQ

What happens if I don't specify files, include, or exclude properties?

TypeScript will default to including all files under the project folder, excluding files in node_modules or specific language output directories.

Why isn't my paths mapping working?

Ensure your baseUrl is correctly specified. Moreover, verify that the path patterns correctly match the project structure.

Can I use both baseUrl and paths without a module bundler?

While you can configure these options in tsconfig.json, actual execution will depend on a module loader or bundler that supports these mappings.